Welcome

 Back to Agent Ransack Home page

Welcome
[Main] [Next]

Welcome to Agent Ransack the professional file searching utility.

Agent Ransack is a tool for finding files and information on your hard drive fast and efficiently. When searching the contents of files Agent Ransack also displays the text found. Users can then quickly browse the results without having to separately open each file!

Agent Ransack provides compelling advantages over similar search tools:
· Regular expressions that allow complex rule based searches.
· Immediate contents results view.
· Various wizards to walk the user through the searching process.

Agent Ransack can be used as a replacement or a companion to the standard Windows Find. Agent Ransack provides both a basic interface, similar to Windows Find, and a more advanced interface for the 'Expert user'. Along with both interfaces come two Wizards.

Search Wizard in the Basic interface walks the user through the information required to perform a search. It provides examples of searches and also gives tips on efficient searching.

Expression Wizard in the Advanced interface walks the user through constructing regular expressions for both file name the file contents searching.

What next? Why not check out the Getting started section or brush up on Regular Expressions.

Questions or Comments?
How was the help file created?

Thank you for using Agent Ransack.


Getting started

Getting started
[Previous] [Main] [Next]

When you start Agent Ransack it should look something like this:

As you can see the Agent Ransack interface is broken up into three main sections:
· Criteria view, used to enter search criteria. This differs depending if Expert User has been checked or not.
· File list view, displays files found during search.
· Contents view, displays the files selected in File List view and, if the user is searching for file by contents, then it also displays contents found within the files. This view is the printable area for the application.

Searching

Once the user has entered the criteria and started the search the searching animation starts. If the user is also searching the contents of the files Agent Ransack shows some progress information so the user can gauge how much longer the search will take.

As files are found they appear in the File list view. If the user was also searching the contents of the files then the user can view lines found within the files by selecting one or more of the found files. The lines found are then displayed in the Contents view for each selected file.


Criteria View

Criteria View

Agent Ransack provides two different interfaces, one for the more experienced computer user, and the other for the regular computer user who doesn't want to deal with the complexities of regular expressions but would like to use other features of Agent Ransack. To switch between the two interfaces toggle the 'Expert User' check box.

The main difference between the two interfaces is the Wizards that the interfaces expose. The Basic interface provides a Wizard to walk the user through the information required for a simple search while the Advanced interface provides a Wizard to walk the user through building regular expressions.

Advanced Interface (default)

With Expert User checked the criteria section should look like this:

Filename, Containing Text, and Look in can all be freely entered or selected from previously used search criteria (note: Agent Ransack retains the last twenty values for each). The 'Expr. Wizard...' buttons open the Expression Wizard to walk the user through writing simple regular expressions.

Basic Interface

With Expert User unchecked the criteria section looks more like the standard Windows Find tool:

The main difference between this and Windows Find is the 'Search Wizard...' button, which opens the Search Wizard to walk the user through entering the criteria required for searching.

Saving

Criteria can be saved through the File->Save menu.


File List View

File List View

As files are found during the search they appear in the File List view. For each file it's name and location are displayed. All files selected in this view are shown in the Contents view (the printable view).

Agent Ransack supports context menus so the user can right click on any found file to list valid operations for that file type, as shown below.


Contents View

Contents View

Any files selected in the File List view are displayed in the Contents view. If the user searched the contents of the files then the contents found in the selected files are also displayed. The user can select one or multiple files from the File List view. To select all the files click Select All from the Edit menu.

Only lines that contain the search text are shown, with the search text highlighted in the appropriate color. The highlight color is blue, by default, but this can be changed to any color through Set Highlight Colour on the Edit menu.

Note: When displaying file contents the line number of each line found within the file is also displayed. This line number is estimated by counting carriage returns within the file and therefore if the file contains non-text information then the line numbers may not be accurate.

Printing

The Contents view is the printable area of the application and prints whatever the user has selected in the File List view. To print this view click Print or Print Preview from the File menu.


Hints & Tips

Hints & Tips

Tip 1: You can search multiple files by using regular expressions or DOS expressions (depending upon the appropriate Regular Expression/DOS Expression setting in the Options tab). e.g.
Searching the file types .cpp, .h, .c, .INL the regular expression would be:
\.(cpp|h|c|INL)$
OR, alternatively as a DOS expression it would be:
.cpp;.h;.c;.INL

Tip 2: Use the exclude expression Options tab option to avoid searching given file types. For example, you can search everything but COM and EXE files by switching the 'Specifies exclude expression' in the options tab and setting the file name to the regular expression:
\.(exe|com)$

Tip 3: Associate the file type SRF with Agent Ransack. Save your most common search criteria as a SRF file and put a shortcut to the file on the Start menu. Then when you open the shortcut Agent Ransack will start up with your most common search options.

Tip 4: You can specify the initial values for Agent Ransack through command line parameters. There is even an option to switch off the GUI (Graphical User Interface) and save the results directly to a file, useful when integrating Agent Ransack with other applications. To see a list of valid command line parameters run:
AgentRansack.exe -h

Tip 5: Word wrapping is expensive, especially when trying to display a lot of contents. If the Contents View display is slow consider switching Word Wrapping off.

Tip 6: Test your regular expressions through the Test->Regular expression menu option.

Tip 7: Agent Ransack works in a two phase process. The first phase grabs a list of files that match the File name criteria. The second phase searches the contents of the files found in the first phase. If many files are found in the first phase Agent Ransack may use a significant amount of memory resources maintaining the list of files. Therefore there is an option 'One Phase Searching' on the Search menu to instruct Agent Ransack to search the contents of the file as soon as the File name is matched, avoiding the maintenance of an internal file list. The only drawback to One Phase Searching is that Agent Ransack cannot display a progress meter. Use this feature for more efficient contents searching of a large group of files (i.e. > 10,000), normally this option is NOT required.

Tip 8: Agent Ransack is integrated with the Windows Shell. Therefore if you want to search a folder you can launch Agent Ransack by simply right-clicking on the folder and selecting 'Agent Ransack...' from the folder's context menu.

Tip 9: Unix and Mac text file formats use a different sequence to mark the end of a line. Windows and DOS use the character sequence CR-LF (Carriage Return - Line Feed) but Unix only uses LF and Mac only uses CR. To instruct Agent Ransack to look for alternative EOL (End of Line) sequences go to the Configuration settings (via the menu option Search->Configuration).

Tip 10: Agent Ransack can search multiple folder paths. In the 'Look In' field separate each folder with ';' e.g. "c:\winnt;c:\tmp".


Questions/Comments ?

Questions/Comments ?
[Previous] [Main] [Next]

We are always pleased to hear from users so if you have a questions or comments about Agent Ransack please feel free to contact us at: comments@agentransack.com

If you would like to obtain a registration code please
visit the web site at: http://www.agentransack.com
OR
email us at: register@agentransack.com (make sure you send your full first and last name.)

Thank you for using Agent Ransack.


Help & Manual software

Help & Manual software

This help file was created using a great product from EC Software called Help & Manual 2 (version 2.5). For further information, and to download an evaluation copy, please visit their web site at: http://www.ec-software.com


Search Wizard

Search Wizard

Search Wizard walks the user through entering the basic search criteria with examples and performance tips.

The user is presented with three pages asking for the following pieces of information:
· Name of the file.
· Contents of the file.
· Location of the file.

On the final page if the 'Start the search automatically' check box is checked the search will begin when the user clicks Finish.


Expression Wizard (Expr Wiz)

Expression Wizard (Expr Wiz)
[Previous] [Main] [Next]

Expression Wizard walks the user through creating a basic regular expression. The Expression Wizard can be used for building expressions to search for either the file name or the file contents.

Note: The term 'string' is used as a generic term referring to either the file name or file contents. Basically a string is any word or group of words which, if you think about it, is exactly what a file name is.

First page (Introducing the Expression Wizard)

The first page of the wizard is just an introduction for the Expression Wizard with notes for the particular type of expression being built (i.e. a note for file name and a different note for file contents).

Second page (Create the Expression)

The second page is where all the work takes place. It should look something like this:

Shown above is an example expression for a file name and will find any file name that includes the phrase 'MyFile' followed by any character followed by any number and finally ending with '.txt', i.e. a text file. Therefore it would find files such as 'Dave_MyFile54.txt' or 'MyFile_Num2.txt' but would not find the files 'MyFile.txt', 'A_MyFile34a.txt', or 'MyFile34.doc'.

If you think back to how regular expressions work the layout of the Expression Wizard should become apparent. A regular expression is built out of a number of 'entries'. There is one beginning entry, multiple main body entries, and one final end entry. Each entry has a specific type:
· Don't know. The value of the entry is unknown. e.g. The beginning of the file name may be unknown.
· Any character. Matches to any single character.
· The character. Matches to a character entered by the user in the Text field.
· Any one of these characters. Matches to any one of the characters entered by the user in the Text field.
· Any character except these. Matches to any character except the ones entered by the user in the Text field.
· The phrase. Matches to the specific phrase entered by the user in the Text field.
· Space(s). Matches to a space.
· Any numeric character. Matches to any numeric character, i.e. 0-9.
· Any text character. Matches to any alphabetic character, i.e. a-z.

Once the user has specified the entry type and the text, if required for the entry type, then the user needs to specify the number of occurrences of that entry:
· Zero or once. The entry type may or may not be there but if it is then it maps to one occurrence.
· Zero or many times. The entry type may or may not be there but if it is then it can map to one or more occurrences.
· Once only. The entry type must be there and is mapped to only one occurrence.
· Once or many times. The entry type must be there and can map to many occurrences.

Note: As the Advanced note on the window describes, the Expression Wizard does not currently provide all the functionality of regular expressions. However, if the user knows how to construct their own regular expressions they can enter the any part of a regular expression by adding an entry of type 'The phrase' and putting the regular expression in the Text field.

Begins with

Begins with section specifies how the string should begin (i.e. in the case of file names this is how the file name should begin). If you don't know or don't want to specify the start of the string just leave this as 'Don't Know'.

Followed by

The main body of the regular expression is specified in the Followed by section. Followed by works slightly differently than the Begins with or Ends with section in that it allows multiple entries. Each entry must be separately added using the Add button. If an entry needs to be modified then the user can click on the entry modify the values and then click the Modify button to update the entry.

The entries can be rearranged using drag and drop.

Ends with

Ends with section specifies how the string should end.

Third page (Warning: Special characters entered)

When the user has finished entering the regular expression the user can normally press Finish to feed the regular expression back to the main search window. However, if the user has entered any special characters (i.e. characters that have special meaning in a regular expressions) in the Text field for any entry then the Finish button actually changes into a Next button and the user is warned that special characters were entered. The user then has two choices, either to have Agent Ransack convert the special characters so that they will not be treated as special (default) or to leave the expression as it is because the user specifically entered special characters.

In the screen shot shown above you can see that this is exactly what happened with the example. The Ending with used the special character '.', the wildcard character, and therefore instead of a Finish button there is a Next button. If you look at the resulting expression you'll see that the '.' has been prefixed with the '\' escape character. This happened automatically because of the default action, which is to convert the special characters so that they are not treated as special. This page (i.e. the third page) allows the user to turn that default action off.


Quick Start

Quick Start

Agent Ransack is a file searching tool based upon a descriptive standard called 'regular expressions' (some times shortened to regexp). Regular expressions provide a concise language to describe exactly what you are searching for. In very basic terms you can split an expression into two parts:
- what you are looking for
- the number of occurrences you want to find of it.

Note: Before following these examples make sure you go to the Options tab and ensure that filename is Regular Expression and NOT DOS Expression.

So let's take an example:
1. I want to find all files named abc, abbc, abbbc, abbbbc etc. So basically I want to find all files that begin with 'a' followed by one or more 'b' then followed by 'c'. The expression would be:
ab+c

Breaking that apart we read:
- find one occurrence of 'a'
- find at least one occurrence of 'b' (the '+' indicates 'one or more')
- find one occurrence of 'c'

The characters that specify the number of occurrences are:
+ one or more
* zero or more
? zero or one

So ab?c would find any file named abc or ac (i.e. there can be zero or one 'b').

A very important regexp character is the period '.' because it matches to ANY character. So a.c would match to aac, abc, acc, adc, aec, afc, a1c, a6c etc. And if we combine that with an occurrence character we can start producing some useful expressions:
dave.*vest

breaks down to:
- find one occurrence of 'd'
- then one occurrence of 'a'
- then one occurrence of 'v'
- then one occurrence of 'e'
- then zero or more occurrences of ANY character
- then one occurrence of 'v'
- then one occurrence of 'e'
- then one occurrence of 's'
- then one occurrence of 't'

and so matches to 'davevest', 'dave vest', 'dave is wearing a vest'.

There are other regexp characters and tricks on the following pages. More detail on regular expressions.


What is a regular expression?

What is a regular expression?
[Previous] [Main] [Next]

A regular expression is a way of describing a group of words (referred to as a 'string'). It allows a user to build a complex set of rules to describe exactly what characteristics the string should have. While this documentation uses the word string you can think of a string as either a filename when searching for a filename using regular expressions, or as text in a document when using a regular expression to search the contents of files.

The simplest regular expression is a sequence of letters, numbers, or both. Such a regular expression matches any string that contains that sequence. For example:

The regular expression `foo' matches any string containing `foo'. So if you wanted to find a file with the letters 'fred' in it the regular expression would simply be 'fred'.

This is obviously a very simple example but you can express complicated rules. For example:

To find a file that begins with 'Dave' or 'Sherry' followed at some point by 'Document' or 'Documents' followed at some point by a number and has a '.doc' extension the expression would be: '^(Dave|Sherry).*Documents?.*[0-9]+.*\.doc$'

This expression would find:
· DavesPrivDocuments_23.doc
· Sherry Documents Num5a.doc
· etc.

Don't worry if the expression above looks confusing because it is. That is why Agent Ransack includes an Expression Wizard to guide you through building regular expressions using common English terms.

For more information please read regular expression basics.

Note: You can test out your expression against the Agent Ransack regular expression engine through the 'Test' -> 'Regular Expression...' menu option.


Regular expression basics

Regular expression basics

Regular expressions use special characters (also known as regular expression operators) to specify rules for strings. A summary of these characters are:

^ Beginning of string
$ End of string
. Any character
[ Start of character list
] End of character list
( Start of expression group
) End of expression group
| ORs two expressions
\ Escape character
* Preceding expression occurs zero or more times
? Preceding expression occurs zero or one times
+ Preceding expression occurs one or more times


*, ?, + (Occurrence characters)

*, ?, + (Occurrence characters)
[Previous] [Main] [Next]

Specifies the number of occurrences of the preceding character or group. In a regular expression there are four possible choices when trying to specify how many occurrences the regular expression should match to:

Zero or one, the '?' character.
Zero or many, the '*' character.
One or many, the '+character.
Exactly one, the character itself not followed by any occurrence character.

For example:

If you entered the filename as the expression 'complaint ?doc' it would find all files that had the word 'complaint' followed by zero or one space followed by 'doc'. Therefore it would find files such as 'my complaint doc.doc' and 'mycomplaintdoc.txt', but would NOT find files such as 'my complaint_doc.doc' or 'my complaint doc.doc'.

If you entered the filename as the expression '^my.*cod$' it would find all files that began with the word 'my' followed by zero or more characters ending with 'doc' (note the use of '^' beginning of string, '.' any character, and '$' end of string special characters). Therefore it would find files such as 'my_note.doc', 'my_owndoc', and 'my_specialfile.doc' but would NOT find 'my_note.txt', 'thisis_my_note.doc'.

If you entered the filename as the expression 'file_[0-9]+' would find all files that had the word 'file_' followed by one or more numbers (note the use of '[' and ']' character list special characters). Therefore it would find files such as 'my_file245.doc' and 'the_file0023.txt' but would NOT find 'a_file_34.txt' or 'some_file 009.txt'.


\ (Escape character)

\ (Escape character)
[Previous] [Main] [Next]

Escape character is used to suppress the special meaning of other special characters.

For example:

The expression 'Dave$' will match a string ending with 'Dave' whereas the expression 'Dave\$' will match a string that contains 'Dave$'. As you can see the escape character suppressed the special meaning of the '$' end of string character.

The expression 'file.txt' will match a string that contains 'file' followed by any character followed by 'txt, whereas the expression 'file\.txt' will match a string that contains 'file.txt'. This time the escape character suppressed the meaning of the special character '.' any character.

Finally, the expression to actually search for the '\' character is preceded with the '\', i.e. suppress the escape character, e.g. to search for '3\4' use the expression '3\\4'.


| (Expression OR)

| (Expression OR)
[Previous] [Main] [Next]

Use the | when either one expression or another will do.

For example:

Both the expressions '(Dave|David) Vest' and 'Dav(e|id) Vest' will match 'Dave Vest' and 'David Vest'

'(1|2|3) (person|people)' will match '1 person' and '2 people' and '3 people' but will not match '4 people' (it will also match '2 person' etc.). Note: this expression could have also been expressed using a character list.


(...) (Expression group)

(...) (Expression group)
[Previous] [Main] [Next]

Parentheses are used for grouping in regular expressions as in arithmetic. They are often used with the '|' OR functionality to group alternatives.

For example:

The expression '12 Mar(ch)? 2000' would find the string '12 March 2000' and '12 Mar 2000'. Note the use of the '?' zero or more occurrence character.

If you entered the filename as the expression '^myfile\.(txt|doc)$' it would find any file that whose name was 'myfile.txt' or 'myfile.doc'. Note the use of the '^' beginning of the string character, the '\' escape character to treat the '.' in '.txt' literally, and the '$' end of the string character.


[...] (Character lists)

[...] (Character lists)
[Previous] [Main] [Next]

Specifies a list of characters that are valid in the string. Characters can be listed individually or a range of characters can be indicated by giving two characters and separating them by a '-'. For example, '[abc]' will match any of the characters 'a', 'b', or 'c'; this is the same as '[a-c]', which uses a range to express the same set of characters.

You can match the characters not within a range by complementing the set. This is indicated by using a '^' as the first character in the list (note: this is the same character as the beginning of string character). For example, '[^5]' will match any character except '5'.

Multiple ranges are allowed. E.g., the list '[A-Z0-9]' is a common way to express the idea of "all alphanumeric characters." To include one of the characters `\', `]', `-' or `^' in a character list use the '\' escape character.

For example:

The expression '[0-9]+' will find any number in a string (note the use of the '+' occurrence character).

The expression '[0-9]+/[0-9]+/[0-9]+' is a expression that could be used to search for dates within a string. Although it does not check the validity of the date it is unlikely that any other string would be match that pattern.


. (Wildcard character)

. (Wildcard character)
[Previous] [Main] [Next]

Matches any single character. It is used to specify an unknown portion in the string. Because the period is used in almost all Windows file names it is very common to forget that it has a very special meaning in regular expressions. If the user wishes to use the period literally in a search it must be preceded by the '\' escape character. For example:

If you entered the filename as the expression 'mydoc.doc' it would find any file that had 'mydoc' followed by any character followed by 'doc'. Therefore although it would find 'mydoc.doc' it would also find 'mydoc1doc' and 'mydocXdox'. If you wanted to just search for 'mydoc.doc' the expression would be 'mydoc\.doc'.

Example:

If you entered the filename as the expression '^mydocument..\.txt$' it would find any file that began with 'mydocument' followed by exactly any two characters and ended with '.txt' (note the use of the '^' beginning of the string character, as the '\' escape character to treat the '.' in '.txt' literally, and the '$' end of the string character). Therefore it would find files such as 'mydocument_1.txt' and 'mydocument1a.txt' but would not find files such as 'mydocument.txt' and 'mydocument_1a.txt'.

The expression 'my.*\.txt' would find any file that includes 'my' followed by any number of characters followed by '.txt' (note the use of '*' to specify zero or more occurrences). Therefore it would find files such as 'my_examples.txt' and 'this is my file.txt.doc' but would not find files such as 'myfile.doc' and 'm_y_file.txt'.


$ (End of string)

$ (End of string)
[Previous] [Main] [Next]

Matches the end of a string (to match the beginning of a string use '^').

For example:

If you entered the filename as the expression 'complaint\.doc$' it would find all files that ended with 'complaint.doc' (note the use of the '\' escape character for the '.'). Therefore it would find files such as 'bank_complaint.doc' and 'my_complaint.doc' but would not find files such as 'some_complaint.txt' or 'some_complaint_2.doc'.


^ (Beginning of string)

^ (Beginning of string)
[Previous] [Main]

Matches the beginning of a string (to match the end of a string use '$').

For example:

If you entered the filename as the expression '^win' it would find all files that began with the name 'win'. Therefore it would find files such as 'winhelp.exe' and 'windows_questions.txt' but would not find files such as 'Copy of winhelp.exe' and 'some_winfile.txt.